Management of MorphIT
Since MorphIT release 3.7.5, an administration console for the MorphIT server has been provided for the administration of MorphIT.
Establishment
The Admin Console is delivered together with MorphIT and is located in the /admin_console directory. NodeJS is also required to start the console.
Before MorphIT 4.0.0
Before starting, the dependencies must be installed in this directory using npm install.
The console can then be started via the start_console.bat It attempts to connect to the endpoint specified in the server configuration under ws.admin. In the delivered state, the configurations match. If the console cannot connect, you must check whether the endpoint configured in the server matches that of the console. (/admin_console/config/config.js & /admin_console/config/custom/config.js)
From MorphIT 4.0.0
The console can be started via morphit start console. The endpoint to which the console connects is defined in /config/config.js & /config/custom/config.js under ws.admin.
The console does not have any authentication mechanisms in its current state. For security reasons, the server therefore only accepts connections from the local machine by default.
Relevant configuration
Server configuration: (/server/config.js & /server/custom/config.js)
As of MorphIT 4.0.0 in (/config/config.js & /config/custom/config.js)
| Name | Default | Description |
|---|---|---|
| ws.admin.port | 8081 | The port on which to accept connections to the Admin Console. |
| ws.admin.enabled | true | Specifies whether the server allows administration via Admin Console at all. |
| ws.admin.reject_remote | true | Specifies whether only connections from the local machine are allowed. |
| ws.admin.allowed_ips 4.16.0 | [] | If reject_remote is set to true, then a list of IP addresses can be defined here that are excluded from this rule. Incoming admin console connections from these IP addresses are then accepted anyway. |
| ws.admin.allow_eval 4.6.1 | true | Allows the execution of the eval command of the Admin Console. In security-critical systems this option should be disabled, because a potential attacker who gains user rights on the machine can use it to gain the rights with which the MorphIT server runs. (Privilege Escalation) |
| ws.classix.shutdown_timeout | 10000 | The maximum time (in ms) that ClassiX instances have to wait for the change to the maintenance mode or when the browser connection is disconnected, before the connection is simply terminated. |
| ws.classix.kill_on_timeout | false | If a ClassiX instance does not end within ws.classix.shutdown_timeout and this value is set to true, the system tries to kill the instance as process via its launcher in addition to disconnecting it. |
| ws.launcher.shutdown_timeout | 10000 | The maximum time (in ms) that Launcher Instances have to wait for the change to the maintenance mode suaber before the connection is simply disconnected. |
| ssl.enabled | true | Specifies the SSL configuration for each port. The exact semantics are described here. |
Admin Console: (/admin_console/config/config.js & /admin_console/config/custom/config.js)
As of MorphIT 4.0.0 superfluous
| Name | Default | Description |
|---|---|---|
| endpoint.ssl | false | Specifies whether or not the admin endpoint in the server runs under SSL. |
| endpoint.host | localhost | Specifies the computer to which the Admin Console should connect. |
| endpoint.port | 8081 | Specifies which port the Admin Console should connect to. |
Use
The console automatically tries to connect to the configured endpoint at startup. If this fails, the configuration should be checked. Once the connection is established, the user is presented with a CMD-like prompt that currently supports the following commands. (The console completes commands when TAB is pressed)
Server Commands
Server commands are logged in the server log.
| Command | Description |
|---|---|
| comment text | Writes a comment in the server log. |
| config get path 4.8.0 | The part of the server configuration reached by the path is displayed as JSON in the Admin Console. If no path is passed, then the entire server configuration is displayed. |
| eval JS code | The specified code is executed in the context of the administration module... This allows you to use the This command can be disabled via ws.admin.allow_eval=false to prevent Privilege Escalation via the eval command in security-critical applications. |
| kill ( classix | launcher | morphit ) ids 4.13.0 | Terminates the specified ClassiX/Launcher instances or disconnects the specified MorphIT connections. The ids are a space-separated list and correspond to the ids from the status command. The Id of the web service configuration can also be specified for stopping/restarting ClassiX web service instances. In addition, * is accepted as a special Id that affects all instances of the type. |
| launch webservice configId 4.16.0 | Attempts to launch a new ClassiX webservice instance for the specified webservice configuration via the connected launcher. This command can be used to override the timeout period in the event of a failed launch and quickly make the web service available again. This command also starts instances if the specified number of web service instances for a configuration has already been reached. In this way, if the load of a web service is high, another instance can be started if necessary. |
| maintenance text | Puts the MorphIT server into maintenance mode. For this purpose, all connected instances (ClassiX/Launcher incl. service) From this point on, the MorphIT directories can be changed as desired. The maintenance server assumes the role of the 3.16.1: 4.15.0 |
| status filter | Queries the status of the server and all connected ClassiX, MorphIT, & Launcher instances. The status command can be filtered by appending to one or more filters: classix launcher morphit queue server strategy webwidget can be restricted to the output of the specified ranges. This can be useful if many instances are connected to the server and the full output would be too long and might be shortened by the limited CMD buffer. |
| test_mode (enable|disable|status) timeout 4.8.0 | Switches the MorphIT server into test mode or deactivates it again. When activating it, a timeout in milliseconds can optionally be passed. After this time has elapsed, the test_mode is automatically deactivated again. Existing MorphIT connections are not disconnected by activating the test mode. |
Local commands
| Command | Description |
|---|---|
| help | Outputs a description of the supported commands. |
| clear | Deletes the text content of the console. |
| exit | Disconnects from the server and terminates the console. |
Command line parameters
From MorphIT 3.20.0
The Admin Console can be started using command line arguments to first execute a sequence of commands and then exit the console, or to accept commands interactively. If a connection error occurs, the console sets an appropriate %ERRORLEVEL%.
| Parameters | Description |
|---|---|
| command line | Executes the specified line as if the user had entered it in the console. If the line contains spaces, enclose it in quotation marks. --cmd and --c can be used as short form of command in the same way. |
| | If this parameter is set, then the console will exit automatically after all commands have been executed. This parameter is equivalent to a command exit as the last parameter. The parameter has no effect if no --command is specified. |
| | Prints a help text for using the Admin Console. |
Test mode of the MorphIT server
The maintenance mode starts a dummy MorphIT server that answers all requests with a rudimentary response and does not require directory access, so the MorphIT installation can be updated without hesitation. If the regular MorphIT server is started afterwards, it replaces this dummy server and MorphIT is fully functional again from this point on and accessible for all clients.
However, after major updates have been applied, it is helpful to be able to test the updated application at your leisure before going live. The test mode was developed for this purpose. It is integrated into the regular MorphIT server and can be activated and deactivated at any time. If the mode is activated, the MorphIT server for certain IPs (default: all non-local IPs) imitates the maintenance server by responding to requests in the same way.
The MorphIT server can be configured to start directly into test mode after a maintenance server is taken over, so that regular users of the system do not notice the change. The admin can then test the updated application for errors before deactivating the test mode and releasing the application for all users.
The test mode is controlled by the following configuration in the server:
'maintenance_test_mode': { 'after_maintenance': false, 'after_start': false, 'auto_disable': false, 'allowed_ips' : [] }
The after_maintenance and after_start options define when the server should automatically switch to test mode. after_start=true means that after each start/restart (even after an error) the server will first switch to test mode, which would mean that regular users would not be able to work with MorphIT before the server is unlocked again in the admin console. after_maintenance=true causes the server to automatically switch to test mode only if it has replaced a previously running maintenance dummy server. This should normally be the most sensible setting.
The server can also be put into test mode at any time from the admin console using the command test_mode enable, but a user may already have connected to the server. Existing connections will not be disconnected when test mode is activated, so the way via the admin console may cause individual users to already be working on the system during tests.
The auto_disable option can alternatively be assigned a duration in milliseconds which specifies after which time the test mode is automatically deactivated again. This option is only taken into account if the test mode was not activated through the admin console, but was automatically activated when the server was started.
In allowed_ips a list of IP addresses (as strings) can be entered. All IPs entered here may also use MorphIT in test mode and will not receive a maintenance message. Even without specifying IP addresses, all connections from localhost are always allowed.
The IP address can be entered as v4 or v6 address, but the server does not perform name resolution. If the access does not work, then you should check in the admin console with the command status morphit, which IP address the client has from the server's point of view. If the server is behind a reverse proxy, then the proxy must set the X-Forwared-For HTTP header and ws.trust_proxy=true must be set in the server configuration so that the IP addresses of the clients can be recognized through the proxy.
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}
;){kind=link}